OpenEdge Development: <br />Web Services Handling Web service operation outputs and inputs

A Web service provides two basic means of exchanging information between a client and the Web service:

Passing strongly typed data through the parameters of its operations.

Passing information in the header of each SOAP request and response message with varying degrees of structure and typing.

For both types of information exchange, it may be necessary to access the XML of the underlying SOAP message in order to complete the necessary exchange of information. The following sections describe when you might need to do this and the 4GL facilities that you can use.

Handling complex operation parameters

As shown in the previous sample (see the "Basic Web service access cycle" section), the WSDL Analyzer provides sufficient documentation to code a 4GL application as a Web service client. Often, the input, output, and return parameters of Web service operations can be mapped from their XML Schema types directly to 4GL data types. When this is the case, handling the data for Web service requests is no more challenging than for an AppServer remote procedure call. The 4GL provides recommended and alternative mappings between all basic XML Schema data types and the data types of the 4GL. If for any reason OpenEdge is unable to map the Web service parameter and corresponding 4GL parameter, it generates a run-time error. For information on the 4GL data type mappings to XML Schema and how they are supported in this release of OpenEdge, see Chapter 8, " Analyzing WSDL for Progress 4GL Access to Web Services."

For more complex data interactions, where a Web service parameter is itself an aggregate of more than one XML Schema data type (known as a complex type), the WSDL Analyzer attempts to identify a Progress 4GL temp-table or ProDataSet definition that maps the XML Schema for the data aggregate. If it recognizes a temp-table or ProDataSet definition that maps the parameter, the Analyzer provides that definition for the parameter. You can then interact with the parameter in the 4GL as the defined temp-table or ProDataSet. If the Analyzer cannot identify such a definition, the Analyzer documents the XML Schema for the parameter passed as a CHARACTER or LONGCHAR.

For complex data that the Analyzer provides only the XML Schema passed as a CHARACTER or LONGCHAR, you must directly access and interpret the XML in the parameter yourself. You can do this by converting between the string representation of the serialized XML parameter and a parsed representation, such as provided using the Document Object Model (DOM) or Simple API for XML (SAX), both supported in the 4GL (see OpenEdge Development: Programming Interfaces ). For more information on XML complex types and how OpenEdge maps them to the 4GL, see Chapter 8, " Analyzing WSDL for Progress 4GL Access to Web Services." For more information on how to work with complex types for Web service input and output parameters, see Chapter 10, " Invoking Web Service Operations from the Progress 4GL."

Handling the information in SOAP headers

Some Web services require that you pay attention to the content of the SOAP header in the SOAP request message, the SOAP response message, or both messages for an operation. This can be a simple task or a complex one, depending on the Web service and its application requirements. OpenEdge supports either situation by giving you access to the content of the SOAP header of any SOAP request or response message.

For a SOAP request message, you can access the SOAP header at a point just after invoking the Web service operation and just prior to when OpenEdge sends the message to the Web service. For a SOAP response message, you can access the SOAP header after the message arrives at your Web service client and just prior to when OpenEdge returns the results of any operation output and return parameters to your 4GL program.

Progress callbacks and callback procedures

The 4GL allows you to set a Progress callback for either or both of the SOAP request and response messages exchanged as part of a Web service operation. A Progress callback specifies an internal procedure that you make available for the calling context to execute as part of a core Progress action, in this case, sending or receiving a SOAP message. The specified internal procedure (callback procedure) provides access to the SOAP header at an appropriate point for a request or response message, depending on the type of callback. From within callback procedure you can access the SOAP header using the required procedure parameter and alter the content as allowed by the type of callback.

SOAP header and SOAP header-entryref objects

A SOAP header is a container for other elements known as SOAP header entries. To access a SOAP header and its SOAP header entries, the 4GL provides two objects: a SOAP header object, which provides access to the header and its header entries, and a SOAP header-entryref object that references a given SOAP header entry and its attributes.

When the WSDL Analyzer documents how to interact with a Web service from the 4GL, it attempts to identify any SOAP header entry that it can map to a Progress 4GL temp-table or ProDataSet. If it can, the Analyzer documents the temp-table or ProDataSet definition that you can use to access the XML in a given SOAP header entry. Then, if you choose, you can read the XML from a SOAP response header entry into the specified temp-table or ProDataSet, work with the contents as 4GL data, and write the XML for the specified temp-table or ProDataSet to a SOAP request header entry, as required. For information on converting data between XML and temp-tables or ProDataSets, see OpenEdge Development: Programming Interfaces .

In many (if not most) cases, the WSDL Analyzer cannot map the XML in a SOAP header entry to a temp-table or ProDataSet. In such a case, the Analyzer documents the XML Schema for the SOAP header entry so you can, build, inspect, or modify the content of the SOAP header entry directly. To inspect or modify the actual content of a SOAP header entry, you must access its underlying XML. The 4GL allows you to access the header entry XML either as a serialized XML string or as a DOM tree, much like you access a complex type parameter (see the "Handling complex operation parameters" section).

Thus, using the available 4GL elements to manipulate DOM trees or XML strings, you can create a SOAP header to use for an outgoing SOAP request message, inspect a SOAP header for an incoming SOAP response message to save header entry values, or modify the SOAP response header for use as a SOAP request header during invocation of a following Web service operation. Whether in the form of XML or 4GL temp-tables and ProDataSets, you typically do most of the processing for SOAP header entries in the specified callback procedure. For information on using callbacks to work with headers for each type of SOAP message, see Chapter 11, " Handling SOAP Message Headers in the Progress 4GL."